Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

NS_DEV_DOCFOR:objc_class:ButtonCell;,ButtonCell

Inherits From:	ActionCell : Cell : Object

Declared In:	appkit/ButtonCell.h

Class Description

ButtonCell is a subclass of ActionCell used to implement the user interface devices of push buttons, switches, and radio buttons, as well as any area of the screen that should send a message to a target when clicked.  ButtonCells are used by the Button and Matrix subclasses of Control.  Matrix is specifically used to hold sets of ButtonCells to create groups of switches or radio buttons.

A ButtonCell is a two-state Cell; it's either ªoffº or ªon,º and can be configured to display the two states differently, with a separate title and/or icon (named NXImage) for either state.  The two states are more often referred to as ªnormalº and ªalternate.º  A ButtonCell's state is also used as its value, so Cell methods that set the value (setIntValue: and so on) actually set the ButtonCell's state to ªonº if the value provided is non-zero (or non-null for strings), and to ªoffº if the value is zero or null.  Similarly, methods that retrieve the value return 1 for the ªonº or alternate state (an empty string in the case of stringValue), or 0 or NULL for the ªoffº or normal state.  Unlike Button, ButtonCell doesn't have setState: or state methods; you have to use setIntValue: or a related method.

A ButtonCell sends its action message to its target once if it's View is clicked and it gets the mouse-down event, but can also send the action message continuously as long as the mouse is held down with the cursor inside the ButtonCell.  The ButtonCell can show that it's being pressed by highlighting in several ways, for example, a bordered ButtonCell can appear pushed into the screen, or the icon or title can change to an alternate form while the ButtonCell is pressed.

A ButtonCell can also have a key equivalent (like a Menu item).  If the Window or Panel that the ButtonCell's View is on is the key window, then it gets the first chance to receive events related to key equivalents.  This is used quite often in modal panels that have an ªOKº Button with a Return sign on them.  Usually a ButtonCell displays a key equivalent as its icon; if you ever set an icon for the ButtonCell, the key equivalent remains, but doesn't get displayed.

For more information on ButtonCell's behavior, see the Button and Matrix class specifications.  

Instance Variables

char *altContents;

union _icon {

	struct _bmap {
		id normal;
		id alternate;
	} bmap; 

	struct _ke {
		id font;
		float descent;
	} ke;

} icon; 

id sound;

struct _bcFlags1 {
	unsigned int pushIn:1;
	unsigned int changeContents:1;
	unsigned int changeBackground:1;
	unsigned int  changeGray:1;
	unsigned int lightByContents:1;
	unsigned int lightByBackground:1;
	unsigned int lightByGray:1;
	unsigned int hasAlpha:1;
	unsigned int bordered:1;
	unsigned int iconOverlaps:1;
	unsigned int horizontal:1;
	unsigned int bottomOrLeft:1;
	unsigned int iconAndText:1;
	unsigned int lastState:1;
	unsigned int iconSizeDiff:1;
	unsigned int iconIsKeyEquivalent:1;

} bcFlags1; 

struct _bcFlags2 {
	unsigned int keyEquivalent:8;
	unsigned int transparent:1;
} bcFlags2;

unsigned short periodicDelay;

unsigned short periodicInterval;

altContents 	The contents shown when the ButtonCell is in its alternate state: a string for a text ButtonCell, an NXImage for an icon-only ButtonCell.  

icon.bmap.normal 	The icon for a ButtonCell that displays both a title and an icon.

icon.bmap.alternate 	The alternate icon for a ButtonCell that displays both a title and an icon.

icon.ke.font 	Font used to draw the key equivalent.

icon.ke.descent 	The descent of descenders in the key equivalent font.

sound 	The Sound played when the ButtonCell gets a mouse-down event.

bcFlags1.pushIn 	If 1, a bordered ButtonCell appears to push into the screen when pressed.

bcFlags1.changeContents 	If 1, the ButtonCell shows its alternate state by displaying its alternate icon and title.

bcFlags1.changeBackground	If 1, the ButtonCell shows its alternate state by swapping the light gray and white pixels in its background.

bcFlags1.changeGray 	If 1, the ButtonCell shows its alternate state by swapping its light gray and white pixels.

bcFlags1.lightByContents 	If 1, the ButtonCell highlights while pressed by displaying its alternate icon and title.

bcFlags1.lightByBackground 	If 1, the ButtonCell highlights by swapping the light gray and white pixels in its background.

bcFlags1.lightByGray 	If 1, the ButtonCell shows its highlighting by swapping its light gray and white pixels.

bcFlags1.hasAlpha 	1 if the ButtonCell's icon has alpha values (transparent pixels).

bcFlags1.bordered 	1 if the ButtonCell has a raised bezel border.

bcFlags1.iconOverlaps 	1 if the icon overlaps the title.

bcFlags1.horizontal 	1 if the icon is to one side of title.

bcFlags1.bottomOrLeft 	1 if the icon is on the left or bottom.

bcFlags1.iconAndText 	1 if the ButtonCell has both an icon and a title.

bcFlags1.lastState 	The state of the ButtonCell when last drawn.

bcFlags1.iconSizeDiff 	1 if the alternate icon is a different size than the normal icon.

bcFlags1.iconIsKeyEquivalent	1 if the key equivalent is drawn as the icon.

bcFlags2.keyEquivalent 	The key equivalent character.

bcFlags2.transparent 	1 if the ButtonCell doesn't draw itself at all.

periodicDelay 	The delay before sending the first action message by a continuous ButtonCell.

periodicInterval 	The interval at which a continuous ButtonCell sends its action.

Method Types

Initializing, copying, and freeing a ButtonCell
- init
- initTextCell:
- initIconCell:
- copyFromZone:
- free

Determining component sizes	- calcCellSize:inRect:
- getDrawRect:
- getTitleRect:
- getIconRect:

Setting the titles	- setTitle:
- setTitleNoCopy:
- title
- setAltTitle:
- altTitle
- setFont:

Setting the icons	- setIcon:
- icon
- setAltIcon:
- altIcon
- setImage:
- image
- setAltImage:
- altImage
- setIconPosition:
- iconPosition

Setting the Sound	- setSound:
- sound

Setting the state	- setDoubleValue:
- doubleValue
- setFloatValue:
- floatValue
- setIntValue:
- intValue
- setStringValue:
- setStringValueNoCopy:
- stringValue

Setting the repeat interval	- setPeriodicDelay:andInterval:
- getPeriodicDelay:andInterval:

Tracking the mouse	- trackMouse:inRect:ofView:

Setting the key equivalent	- setKeyEquivalent:
- setKeyEquivalentFont:
- setKeyEquivalentFont:size:
- keyEquivalent

Setting parameters	- setParameter:to:
- getParameter:

Modifying graphic attributes	- setBordered:
- isBordered
- setTransparent:
- isTransparent
- isOpaque

Modifying display behavior	- setType:
- setHighlightsBy:
- highlightsBy
- setShowsStateBy:
- showsStateBy

Simulating a click	- performClick:

Displaying the ButtonCell	- drawInside:inView:
- drawSelf:inView:
- highlight:inView:lit:

Archiving	- read:
- write:

Instance Methods

NS_DEV_DOCFOR:objc_method:[ButtonCell-altIcon];,altIcon

- (const char *)altIcon

Returns the name of the NXImage that appears on the ButtonCell when it's in its alternate state, or NULL if there is no alternate icon or the NXImage has no name.  This NXImage is displayed only for ButtonCells that highlight or show their alternate state by displaying their alternate contents (as opposed to simply lighting or pushing in).

See also:  - setAltIcon:, - setIconPosition:, - altImage, - icon, - image, - setType:

NS_DEV_DOCFOR:objc_method:[ButtonCell-altImage];,altImage

- altImage

Returns the NXImage that appears on the ButtonCell when it's in its alternate state, or nil if there is no alternate NXImage.  This ButtonCell only displays its alternate NXImage if it highlights or shows its alternate state by displaying its alternate contents.

See also:  - setAltImage:, - setIconPosition:, - altIcon, - image, - icon, - setType:

NS_DEV_DOCFOR:objc_method:[ButtonCell-altTitle];,altTitle

- (const char *)altTitle

Returns the string that appears on the ButtonCell when it's in its alternate state, or NULL if there isn't one.  The alternate title is only displayed if the ButtonCell highlights or shows its alternate state by displaying its alternate contents.

See also:  - setAltTitle:, - title, - setType:

NS_DEV_DOCFOR:objc_method:[ButtonCell-calcCellSize:inRect:];,calcCellSize:inRect:

- calcCellSize:(NXSize *)theSize inRect:(const NXRect *)aRect

Returns self, and by reference in theSize the minimum width and height required for displaying the ButtonCell in aRect.  This minimum size is the larger of the sizes required for displaying the normal contents or the alternate contents, plus any space needed to display a border.

See also:  - getDrawRect:, - getIconRect:, - getTitleRect:

NS_DEV_DOCFOR:objc_method:[ButtonCell-copyFromZone:];,copyFromZone:

- copyFromZone:(NXZone *)zone

Allocates, initializes, and returns a copy of the receiving ButtonCell.  The copy is allocated from zone and is given the same data as the receiver.

NS_DEV_DOCFOR:objc_method:[ButtonCell-doubleValue];,doubleValue

- (double)doubleValue

Returns 0.0 if the ButtonCell is in its normal state, 1.0 if the it's in its alternate state.

See also:  - setDoubleValue:, - floatValue, - intValue, - stringValue

NS_DEV_DOCFOR:objc_method:[ButtonCell-drawInside:inView:];,drawInside:inView:

- drawInside:(const NXRect *)aRect inView:controlView

Draws the inside of the ButtonCell (the title, icon, and their background, but not the border) in aRect within controlView.  aRect should be the same rectangle passed to drawSelf:inView:.  The PostScript focus must be locked on controlView when this message is sent.  This method is invoked by drawSelf:inView: and by the Control classes' drawCellInside: method.  It's provided so that when a ButtonCell's state is set (with setIntValue:, for example), a minimal update of the ButtonCell's visual appearance can occur.  Returns self.

If you subclass ButtonCell and override drawSelf:inView:, you must also override this method.  However, you are free to override only this method and not drawSelf:inView: if your subclass doesn't draw outside the area that ButtonCell draws in.

See also:  - drawInside:inView: (Cell), - drawSelf:inView:, - lockFocus (View)

NS_DEV_DOCFOR:objc_method:[ButtonCell-drawSelf:inView:];,drawSelf:inView:

- drawSelf:(const NXRect *)cellFrame inView:controlView

Displays the ButtonCell in cellFrame within controlView.  The PostScript focus must be locked on controlView when this message is sent.  Draws the border of the ButtonCell if necessary, then invokes drawInside:inView:.  Returns self.

See also:  - drawInside:inView:, - lockFocus (View)

NS_DEV_DOCFOR:objc_method:[ButtonCell-floatValue];,floatValue

- (float)floatValue

Returns 0.0 if the ButtonCell is in its normal state, 1.0 if it's in its alternate state.

See also:  - setFloatValue:, - doubleValue, - intValue, - stringValue

NS_DEV_DOCFOR:objc_method:[ButtonCell-free];,free

- free

Frees the memory used by the ButtonCell and returns nil.

NS_DEV_DOCFOR:objc_method:[ButtonCell-getDrawRect:];,getDrawRect:

- getDrawRect:(NXRect *)theRect

Returns self and, by reference in theRect the bounds of the area into which the title and icon (not including the border) are drawn.  You must pass the bounds of the ButtonCell in theRect (the same bounds calculated by calcCellSize:inRect: and passed to drawSelf:inView:).  This method assumes that the ButtonCell is being drawn in a flipped View.

See also:  - getIconRect:, - getTitleRect:, - calcCellSize:inRect:

NS_DEV_DOCFOR:objc_method:[ButtonCell-getIconRect:];,getIconRect:

- getIconRect:(NXRect *)theRect

Returns self and, by reference in theRect, the bounds of the area into which the icon of the ButtonCell will be drawn.  This will be the larger of the bounds for the normal and the alternate icons.  If the ButtonCell has no icon, then theRect will be completely zeroed.  You must pass the bounds of the ButtonCell in theRect (the same bounds calculated by calcCellSize:inRect: and passed to drawSelf:inView:).  This method assumes that the ButtonCell is being drawn in a flipped View.  Returns self.

See also:  - getTitleRect:, - getDrawRect:, - calcCellSize:inRect:

NS_DEV_DOCFOR:objc_method:[ButtonCell-getParameter:];,getParameter:

- (int)getParameter:(int)aParameter

Returns the value of one of the frequently accessed flags for a ButtonCell.  See setParameter:to: for a list of the parameters and corresponding methods.  Since the parameters are also accessible through normal querying methods, you shouldn't need to use this method often.

See also:  - setParameter:to:

NS_DEV_DOCFOR:objc_method:[ButtonCell-getPeriodicDelay:andInterval:];,getPeriodicDelay:andInterval:

- getPeriodicDelay:(float *)delay andInterval:(float *)interval

Returns self, and by reference the delay and interval periods for a continuous ButtonCell.  delay is the amount of time (in seconds) that a continuous ButtonCell will pause before starting to periodically send action messages to the target object.  interval is the amount of time (also in seconds) between those messages.

See also:  - setContinuous: (Cell), - setPeriodicDelay:andInterval:

NS_DEV_DOCFOR:objc_method:[ButtonCell-getTitleRect:];,getTitleRect:

- getTitleRect:(NXRect *)theRect

Returns self and, by reference in theRect a copy of the bounds of the area into which the ButtonCell's title will be drawn.  This will be the larger of the bounds for the normal and the alternate titles.  If the ButtonCell has no title, then theRect will be completely zeroed.  You must pass the bounds of the ButtonCell in theRect (the same bounds calculated by calcCellSize:inRect: and passed to drawSelf:inView:).  This method assumes that the ButtonCell is being drawn in a flipped View.

See also:  - getIconRect:, - getDrawRect:, - calcCellSize:inRect:

NS_DEV_DOCFOR:objc_method:[ButtonCell-highlight:inView:lit:];,highlight:inView:lit:

- highlight:(const NXRect *)cellFrame
inView:controlView
lit:(BOOL)flag

Displays the ButtonCell in cellFrame if its highlight state is not equal to flag.  The PostScript focus must be locked on controlView when this method is invoked.  If flag is YES, the ButtonCell is displayed as highlighted.  How this is done depends on how the ButtonCell has been configured; see the description of setHighlightsBy: for the possible manners of highlighting.  This method does nothing if the ButtonCell is disabled or transparent.  Returns self.

See also:  - lockFocus (View)

NS_DEV_DOCFOR:objc_method:[ButtonCell-highlightsBy];,highlightsBy

- (int)highlightsBy

Returns the logical OR of flags that indicate the way the ButtonCell highlights when it gets a mouse-down event.  See setHighlightsBy: for the list of flags.

See also:  - setHighlightsBy:, - showStateBy, - setShowsStateBy:

NS_DEV_DOCFOR:objc_method:[ButtonCell-icon];,icon

- (const char *)icon

Returns the name of the NXImage that appears on the ButtonCell when it's in its normal state, or NULL if there is no such NXImage or the NXImage doesn't have a name.  A ButtonCell that doesn't display its alternate contents to highlight or show its alternate state will always display its normal icon.

See also:  - setIcon:, - setIcon:position:, - setIconPosition:, - image, - altIcon, - altImage, - setType:

NS_DEV_DOCFOR:objc_method:[ButtonCell-iconPosition];,iconPosition

- (int)iconPosition

Returns the position of the ButtonCell's icon (if any).  See setIconPosition: for a list of the valid positions.

See also:  - setIconPosition:

NS_DEV_DOCFOR:objc_method:[ButtonCell-image];,image

- image

Returns the NXImage that appears on the ButtonCell when it's in its normal state, or nil if there is no such NXImage.  This NXImage is always displayed on a ButtonCell that doesn't change its contents when highlighting or showing its alternate state.

See also:  - setImage:, - setIconPosition:, - icon, - altImage, - altIcon, - setType:

NS_DEV_DOCFOR:objc_method:[ButtonCell-init];,init

- init

Initializes and returns the receiver, a new text ButtonCell, with the title ªButtonº aligned in the center.  The new ButtonCell is enabled, but has no icon, tag, target, action, or key equivalent associated with it.  The new ButtonCell is bordered, and is of type NX_MOMENTARYPUSH.

See also:  - initIconCell:, - initTextCell:

NS_DEV_DOCFOR:objc_method:[ButtonCell-initIconCell:];,initIconCell:

- initIconCell:(const char *)iconName

Initializes and returns the receiver, a new ButtonCell instance that displays an icon.  iconName is the name of an NXImage that will be used for the Button's icon.  The new ButtonCell is enabled, bordered, and is of type NX_MOMENTARYPUSH.  

This is the designated initializer for ButtonCells that display icons.

See also:  - initTextCell:, - init

NS_DEV_DOCFOR:objc_method:[ButtonCell-initTextCell:];,initTextCell:

- initTextCell:(const char *)aString

Initializes and returns the receiver, a new ButtonCell instance that displays a title.  aString is the title that will be used; it will be displayed in the user's default system font (as set with the Preferences application), 12.0 point size, and aligned in the center.  The new ButtonCell is enabled, is bordered, and is of type NX_MOMENTARYPUSH.

This is the designated initializer for ButtonCells that display titles.

See also:  - initIconCell:, - init

NS_DEV_DOCFOR:objc_method:[ButtonCell-intValue];,intValue

- (int)intValue

Returns 0 if the ButtonCell is in its normal state, 1 if in its alternate state.

See also:  - setIntValue:, - doubleValue, - floatValue, - stringValue

NS_DEV_DOCFOR:objc_method:[ButtonCell-isBordered];,isBordered

- (BOOL)isBordered

Returns YES if the ButtonCell has a border, NO if not.  A ButtonCell's border isn't the single line of most other Cells' borders; instead, it's a raised bezel (ªbezelº usually refers to a depressed bezel, as seen on FormCells, for example).

See also:  - setBordered:

NS_DEV_DOCFOR:objc_method:[ButtonCell-isOpaque];,isOpaque

- (BOOL)isOpaque

Returns YES if the ButtonCell draws over every pixel in its frame, NO if not.  The ButtonCell is opaque only if it is not transparent and if it has a border.

See also:  - isBordered, - setBordered:, - isTransparent, - setTransparent:

NS_DEV_DOCFOR:objc_method:[ButtonCell-isTransparent];,isTransparent

- (BOOL)isTransparent

Returns YES if the ButtonCell is transparent, NO if not.  A transparent ButtonCell never draws anything, but it does receive mouse-down events and track the mouse properly.

See also:  - setTransparent:, - isOpaque

NS_DEV_DOCFOR:objc_method:[ButtonCell-keyEquivalent];,keyEquivalent

- (unsigned short)keyEquivalent

Returns the key equivalent character of the ButtonCell, or 0 if one hasn't been set.

See also:  - setKeyEquivalent:, - setKeyEquivalentFont:, - setKeyEquivalentFont:size:

NS_DEV_DOCFOR:objc_method:[ButtonCell-performClick:];,performClick:

- performClick:sender

If this ButtonCell is contained in a Control, then invoking this method causes the ButtonCell to act as if the user had clicked it.

NS_DEV_DOCFOR:objc_method:[ButtonCell-read:];,read:

- read:(NXTypedStream *)stream

Reads the ButtonCell from the typed stream stream.  Returns self.

See also:  - write:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setAltIcon:];,setAltIcon:

- setAltIcon:(const char *)iconName

Sets the ButtonCell's alternate icon by name; iconName is the name of the NXImage to be displayed.  Has the ButtonCell redrawn if possible, and returns self.

A ButtonCell's alternate icon is only displayed if the ButtonCell highlights or shows its alternate state by changing its contents.

See also:  - altIcon, - setIconPosition:, - setAltImage:, - setIcon:, - setImage:, + findImageNamed: (NXImage), - setType:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setAltImage:];,setAltImage:

- setAltImage:altImage

Sets the Button's alternate icon by id; altImage is the NXImage to be displayed.  Has the ButtonCell redrawn if possible, and returns self.

A ButtonCell displays its alternate NXImage only if it highlights or displays its alternate state by using its alternate contents.

See also:  - altImage, - setIconPosition:, - setAltIcon:, - setImage:, - setIcon:, - setType:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setAltTitle:];,setAltTitle:

- setAltTitle:(const char *)aString

Sets the title that the ButtonCell displays in its alternate state to aString.  Doesn't display the ButtonCell even if autodisplay is on in the ButtonCell's View.  Returns self.

The alternate title is shown only if the ButtonCell changes its contents when highlighting or displaying its alternate state.

See also:  - altTitle:, - setTitle:, - setType:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setBordered:];,setBordered:

- setBordered:(BOOL)flag

If flag is YES, the ButtonCell displays a border; if NO, the If flag is YES, the ButtonCell displays a border; if NO, the ButtonCell doesn't display a border.  A ButtonCell's border is not the single line or most other Cells' borders; instead, it's a raised bezel (ªbezelº usually refers to a depressed bezel, as seen on FormCells, for example).  Your code shouldn't use setBezeled: with a ButtonCell.  This method redraws the ButtonCell if the bordered state changes.  Returns self.

See also:  - isBordered

NS_DEV_DOCFOR:objc_method:[ButtonCell-setDoubleValue:];,setDoubleValue:

- setDoubleValue:(double)aDouble

If aDouble is 0.0, sets the ButtonCell's state to 0 (the normal state); if aDouble is nonzero, sets it to 1 (the alternate state).  Returns self.

See also:  - doubleValue, - setFloatValue:, - setIntValue:, - setStringValue:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setFloatValue:];,setFloatValue:

- setFloatValue:(float)aFloat

If aDouble is 0.0, sets the ButtonCell's state to 0 (the normal state); if aDouble is nonzero, sets it to 1 (the alternate state).  Returns self.

See also:  - floatValue, - setDoubleValue:, - setIntValue:, - setStringValue:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setFont:];,setFont:

- setFont:fontObject

Sets the Font used to displaying the title and alternate title.  Does nothing if the cell has no title or alternate title.  Returns self.

If the ButtonCell has a key equivalent, its Font is not changed, but the key equivalent's Font size is changed to match the new title Font.

See also:  - setKeyEquivalentFont:, - setKeyEquivalentFont:size:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setHighlightsBy:];,setHighlightsBy:

- setHighlightsBy:(int)aType

Sets the way the ButtonCell highlights itself while pressed, and returns self.  aType can be the logical OR of one or more of the following constants:

NX_PUSHIN (the default):  The ButtonCell ªpushes inº when pressed if it has a border.

NX_NONE:  The ButtonCell doesn't change.  This flag is ignored if any others are set in aType.

NX_CONTENTS:  The ButtonCell displays its alternate icon and/or title.

NX_CHANGEGRAY:  The ButtonCell swaps the light gray and white pixels on the its background and icon.

NX_CHANGEBACKGROUND:  Same as NX_CHANGEGRAY, but only background pixels are changed.

If both NX_CHANGEGRAY and NX_CHANGEBACKGROUND are specified, both are recorded, but which behavior is used depends on the ButtonCell's icon.  If there is no icon, or if the icon has no alpha (tranparency) data, NX_CHANGEGRAY is used.  If the icon does have alpha data, NX_CHANGEBACKGROUND is used; this allows the gray/white swap of the background to show through the icon's transparent pixels.

See also:  - highlightsBy, - setShowsStateBy:, - showsStateBy

NS_DEV_DOCFOR:objc_method:[ButtonCell-setIcon:];,setIcon:

- setIcon:(const char *)iconName

Sets the Button's icon by name; iconName is the name of the NXImage to be displayed.  Redraws the Button's inside and returns self.

A ButtonCell's icon is displayed when the ButtonCell is in its normal state, or always if the ButtonCell doesn't highlight or show state by changing its contents.

See also:  - setIcon:position:, - icon, - setIconPosition:, - setImage:, - setAltIcon:, - setAltImage:, + findImageNamed: (NXImage), - setType:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setIconPosition:];,setIconPosition:

- setIconPosition:(int)aPosition

Sets the position of the icon when a ButtonCell simultaneously displays both text and an icon.  aPosition can be one of the following constants:

NX_TITLEONLY	title only (no icon on the Button) 
NX_ICONONLY	icon only (no text on the Button) 
NX_ICONLEFT	icon is to the left of the text 
NX_ICONRIGHT	icon is to the right of the text 
NX_ICONBELOW	icon is below the text 
NX_ICONABOVE	icon is above the text 
NX_ICONOVERLAPS	icon and text overlap (text drawn over icon)

If the position is top or bottom, the alignment of the text will be changed to NX_CENTERED.  This behavior can be overridden with a subsequent setAlignment: method.  Redraws the Button's inside and returns self.

See also:  - iconPosition, - setAlignment: (ActionCell)

NS_DEV_DOCFOR:objc_method:[ButtonCell-setImage:];,setImage:

- setImage:image

Sets the Button's icon by id; image is the NXImage to be displayed.   Redraws the Button's inside and returns self.

A ButtonCell's NXImage is displayed when the ButtonCell is in its normal state, or all the time for a ButtonCell that doesn't change its contents when highlighting or displaying its alternate state.

See also:  - image, - setIconPosition:, - setIcon:, - setAltImage:, - setAltIcon:, - setType:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setIntValue:];,setIntValue:

- setIntValue:(int)anInt

Sets the ButtonCell's state to 1 if anInt is nonzero, 0 otherwise.  Returns self.

See also:  - intValue, - setDoubleValue:, - setFloatValue:, - setStringValue:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setKeyEquivalent:];,setKeyEquivalent:

- setKeyEquivalent:(unsigned short)charCode

Sets the key equivalent character of the ButtonCell.  Has the ButtonCell redrawn if needed.  The key equivalent isn't displayed if the icon position is set to NX_TITLEONLY, NX_ICONONLY or NX_ICONOVERLAPS.  Returns self.

The key equivalent isn't displayed on a ButtonCell that has an icon.  To make sure it gets displayed, set the image and alternate image to nil before using this method.

See also:  - keyEquivalent, - setKeyEquivalentFont:, - setKeyEquivalentFont:size:, - performKeyEquivalent: (Button, Matrix classes)

NS_DEV_DOCFOR:objc_method:[ButtonCell-setKeyEquivalentFont:];,setKeyEquivalentFont:

- setKeyEquivalentFont:fontObject

Sets the Font used to draw the key equivalent, and has the ButtonCell redrawn if possible.  Does nothing if there is already an icon associated with this ButtonCell.  The default Font is the same as that used to draw the title.  Returns self.

See also:  - setKeyEquivalentFont:size:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setKeyEquivalentFont:size:];,setKeyEquivalentFont:size:

- setKeyEquivalentFont:(const char *)fontName size:(float)fontSize

Sets by name and size the font used to draw the key equivalent, and has the ButtonCell redrawn if possible.  Does nothing if there is already an icon associated with this ButtonCell.  The default Font is the same as that used to draw the title.  Returns self.

See also:  - setKeyEquivalentFont:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setParameter:to:];,setParameter:to:

- setParameter:(int)aParameter to:(int)value

Sets the value of one of a number of frequently accessed flags for a ButtonCell to value, and returns self.  You don't normally need to use this method since all of these flags can be set  through specific methods (for example, setEnabled:, setHighlightsBy:, and so on).  The following table lists each constant used to identify a parameter with the methods for setting and retrieving the value for that parameter:

Parameter Constant	Equivalent Methods

NX_CELLDISABLED	setEnabled:, isEnabled
NX_CELLSTATE	setState:, state
NX_CELLHIGHLIGHTED	highlight:inView:lit:, isHighlighted
NX_CELLEDITABLE	setEditable:, isEditable
NX_BUTTONINSET	(noneÐsee below)
NX_CHANGECONTENTS	setShowsStateBy:, showsStateBy
NX_CHANGEBACKGROUND	setShowsStateBy:, showsStateBy
NX_CHANGEGRAY	setShowsStateBy:, showsStateBy
NX_LIGHTBYCONTENTS	setHighlightsBy:, highlightsBy
NX_LIGHTBYBACKGROUND	setHighlightsBy:, highlightsBy
NX_LIGHTBYGRAY	setHighlightsBy:, highlightsBy
NX_PUSHIN	setHighlightsBy:, highlightsBy
NX_OVERLAPPINGICON	setIconPosition:, iconPosition
NX_ICONHORIZONTAL	setIconPosition:, iconPosition
NX_ICONONLEFTORBOTTOM	setIconPosition:, iconPosition
NX_ICONISKEYEQUIVALENT	(see below)

NX_BUTTONINSET is the inset of the ButtonCell's icon from its frame.  You can find out if a ButtonCell's icon is its key equivalent by checking that both the image and altImage methods return nil, and that the keyEquivalent method returns a nonzero value.  Your code should never set the NX_ICONISKEYEQUIVALENT parameter; always use the setKeyEquivalent: method, removing the ButtonCell's icon if necessary.

See also:  - getParameter:, - setKeyEquivalent:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setPeriodicDelay:andInterval:];,setPeriodicDelay:andInterval:

- setPeriodicDelay:(float )delay andInterval:(float )interval

Sets the message delay and interval for the ButtonCell.  These two values are used if the ButtonCell has been setÐby a setContinuous: messageÐto continuously send its action message to its target object while tracking the mouse.  delay is the amount of time (in seconds) that a continuous ButtonCell will pause before starting to periodically send action messages to the target object.  interval is the amount of time (also in seconds) between those messages.  Returns self.

The maximum value allowed for both delay and the interval is 60.0 seconds.

See also:  - getPeriodicDelay:andInterval:, - setContinuous: (Cell)

NS_DEV_DOCFOR:objc_method:[ButtonCell-setShowsStateBy:];,setShowsStateBy:

- setShowsStateBy:(int)aType

Sets the way the ButtonCell indicates its alternate state.  aType should be the logical OR of one or more of the following constants:

NX_NONE (the default):  The ButtonCell doesn't change.  This flag is ignored if any others are set in aType.

NX_CONTENTS:  The ButtonCell displays its alternate icon and/or title.

NX_CHANGEGRAY:  The ButtonCell swaps the light gray and white pixels on its background and icon.

NX_CHANGEBACKGROUND:  Same as NX_CHANGEGRAY, but only the background pixels are changed.

If both NX_CHANGEGRAY and NX_CHANGEBACKGROUND are specified, both are recorded, but the actual behavior depends on the ButtonCell's icon.  If there is no icon, or if the icon has no alpha (tranparency) data, NX_CHANGEGRAY is used.  If the icon exists and has alpha data, NX_CHANGEBACKGROUND is used; this allows the gray/white swap of the background to show through the icon's transparent pixels.

See also:  - showsStateBy, - setHighlightsBy:, - highlightsBy

NS_DEV_DOCFOR:objc_method:[ButtonCell-setSound:];,setSound:

- setSound:aSound

Sets the Sound that will be played when the mouse goes down in the ButtonCell, and whenever the cursor re-enters the ButtonCell while tracking.  Be sure to link against the Sound Kit if you use a Sound object.  Returns self.

See also:  - sound

NS_DEV_DOCFOR:objc_method:[ButtonCell-setStringValue:];,setStringValue:

- setStringValue:(const char *)aString

Sets the ButtonCell's state to 1 if aString is non-null (even if the string is empty), 0 otherwise.  Returns self.

See also:  - setStringValueNoCopy:, - stringValue

NS_DEV_DOCFOR:objc_method:[ButtonCell-setStringValueNoCopy:];,setStringValueNoCopy:

- setStringValueNoCopy:(const char *)aString

Sets the ButtonCell's state to 1 if aString is non-null (even if the string is empty), 0 otherwise.  Returns self.

See also:  - setStringValue:, - stringValue, - setDoubleValue:, - setFloatValue:, - setIntValue:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setTitle:];,setTitle:

- setTitle:(const char *)aString

Sets the title displayed by the ButtonCell when in its normal state to aString.  This title is always shown on ButtonCells that don't use their alternate contents when highighting or displaying their alternate state.  Redraws the Button's inside and returns self.

See also:  - setTitleNoCopy:, - title, - setAltTitle:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setTitleNoCopy:];,setTitleNoCopy:

- setTitleNoCopy:(const char *)aString

Similar to setTitle: but does not make a copy of aString.  Returns self.

See also:  - setTitle:

NS_DEV_DOCFOR:objc_method:[ButtonCell-setTransparent:];,setTransparent:

- setTransparent:(BOOL)flag

Sets whether the ButtonCell is transparent.  Returns self.

A transparent ButtonCell never draws, but does track the mouse and send its action normally.  A transparent ButtonCell is useful for sensitizing an area on the screen so that an action gets sent to a target when the area receives a mouse click.

See also:  - isTransparent, - isOpaque

NS_DEV_DOCFOR:objc_method:[ButtonCell-setType:];,setType:

- setType:(int)aType

Sets the way the ButtonCell highlights while pressed, and how it shows its state.  Redraws the ButtonCell if possible and returns self.  aType can be one of the following constants (as described in the Button class specification's setType: method description):

NX_MOMENTARYPUSH
NX_MOMENTARYCHANGE
NX_PUSHONPUSHOFF
NX_ONOFF
NX_TOGGLE
NX_SWITCH
NX_RADIOBUTTON

See also:  - setType: (Button), - setHighlightsBy:, - setShowsStateBy:

NS_DEV_DOCFOR:objc_method:[ButtonCell-showsStateBy];,showsStateBy

- (int)showsStateBy

Returns the logical OR of flags that indicate the way the ButtonCell shows its alternate state.  See setShowsStateBy: for the list of flags.

See also:  - setShowsStateBy:, - highlightsBy, - setHighlightsBy:

NS_DEV_DOCFOR:objc_method:[ButtonCell-sound];,sound

- sound

Returns the Sound played when the ButtonCell gets a mouse-down event, and whenever the cursor re-enters the ButtonCell while tracking.

See also:  - setSound:

NS_DEV_DOCFOR:objc_method:[ButtonCell-stringValue];,stringValue

- (const char *)stringValue

Returns ªº (an empty string) if the ButtonCell's state is 1 (the alternate state), or NULL if the state is 0 (the normal state).

See also:  - setStringValue:, - setStringValueNoCopy:, - doubleValue, - floatValue, - intValue

NS_DEV_DOCFOR:objc_method:[ButtonCell-title];,title

- (const char *)title

Returns the title displayed on the Button when it's in its normal state, or always if the Button doesn't use its alternate contents for highlighting or displaying the alternate state.  Returns NULL if there is no title.

See also:  - setTitle:, - setTitleNoCopy:

NS_DEV_DOCFOR:objc_method:[ButtonCell-trackMouse:inRect:ofView:];,trackMouse:inRect:ofView:

- (BOOL)trackMouse:(NXEvent *)theEvent
inRect:(const NXRect *)cellFrame
ofView:controlView

Tracks the mouse by starting the Sound (if any) and sending trackMouse:inRect:ofView to super with the same arguments.  When super's method returns, stops the Sound if needed and returns YES if the mouse Button went up with the cursor in the cell, NO otherwise.  This method returns if the cursor leaves the bounds of the ButtonCell.

See also:  - trackMouse:inRect:ofView: (Cell)

NS_DEV_DOCFOR:objc_method:[ButtonCell-write:];,write:

- write:(NXTypedStream *)stream

Writes the receiving ButtonCell to the typed stream stream.  Returns self.  

See also:  - read: